Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update octavia.rst #1362

Open
wants to merge 9 commits into
base: stackhpc/2024.1
Choose a base branch
from
Open

Update octavia.rst #1362

wants to merge 9 commits into from

Conversation

MaxBed4d
Copy link
Contributor

@MaxBed4d MaxBed4d commented Nov 5, 2024

Update to the Octavia docs to provide some details on the deployment.

MaxBed4d and others added 4 commits August 30, 2024 11:23
Updating the Octavia docs to explain how to deploy it, alongside other important settings.
More changes to the docs.
@MaxBed4d MaxBed4d requested a review from a team as a code owner November 5, 2024 14:36
doc/source/operations/octavia.rst Outdated Show resolved Hide resolved

.. _Deploying Octavia:

Deploying Octavia
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you restructure this into a sequence of individual steps? See for example the Multinode page which goes through a few things step-by-step

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems a little unnecessary for this because it would end up being 2 steps; this is more to make people aware of the various configs which could snag the deployment.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think at the moment it misses a few important steps, in particular "It of course goes without saying that the network should exist in networks.yml" is a pretty big thing to gloss over.

So for example you could have:

  1. Where to enable the service in kolla.yml
  2. How to define the octavia network in networks.yml
  3. How to define network interfaces for controllers
  4. What to check for neutron provider networks
  5. How to select the right driver(s), and the differences between Amphora vs OVN
  6. How to properly configure the Amphora driver

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please also keep in mind that simple, clear instructions make for the best docs. try to stay away from wordyness.

For example:

Much like any other Kolla managed service, the method of deploying Octavia is as simple
as ...

could be written as:

To enable Octavia, set ...

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have an idea on how to make a nice comprehensive list. Regarding the wordyness, in some cases it is intentional, in the example provided mentioning its similarity to other Kolla managed services will give users a lot of context as to what to expect, as long as they have deployed at least one service before; in addition to reinforcing the steps for deploying services. In other cases, I agree and some sentences are wordy without adding anything.

doc/source/operations/octavia.rst Outdated Show resolved Hide resolved
doc/source/operations/octavia.rst Outdated Show resolved Hide resolved
@MaxBed4d MaxBed4d requested a review from MoteHue November 6, 2024 10:25
@MaxBed4d MaxBed4d force-pushed the octavia_docs branch 14 times, most recently from 947d6f0 to a2f07d0 Compare November 7, 2024 15:40
doc/source/operations/octavia.rst Outdated Show resolved Hide resolved
@Alex-Welsh Alex-Welsh added documentation Improvements or additions to documentation Caracal Targets the Caracal OpenStack release labels Nov 15, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Caracal Targets the Caracal OpenStack release documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants